Feat/v2 wallet linkage - #388

Summary

Implemented the V2 wallet-to-user ownership boundary with a canonical wallet linkage model, signature-based linking and unlinking, verification history, and recovery safeguards that preserve wallet ownership without introducing centralized account takeover.

Architecture

• Established a canonical wallet ownership record as the authoritative application-level representation of wallet-to-user linkage.
• Added verification timestamps and audit history to provide traceability for ownership changes.
• Kept smart contracts authoritative for protocol claims, verification, settlement, rewards, treasury, and governance.
• Audited overlapping legacy wallet/account linkage paths and documented which paths are reused, replaced, or deprecated.
• Kept the resulting state rebuildable without introducing backend authority over protocol state.

Changes

• Added the canonical wallet ownership persistence model.
• Added wallet verification metadata and ownership-change audit records.
• Implemented wallet linking through fresh wallet signatures.
• Implemented wallet unlinking with fresh signature verification and authorization checks.
• Added protection against replaying previously valid signatures or challenges.
• Added validation for wallet addresses, signature payloads, ownership state, and request boundaries.
• Implemented safe recovery boundaries that do not allow centralized operators to assume ownership of a wallet identity.
• Added appropriate API schemas, migrations, and configuration updates.
• Added observability around wallet-link and recovery operations without logging signatures, secrets, or sensitive authentication material.
• Updated documentation describing wallet ownership, linking, unlinking, and recovery behavior.

Security & Integrity

• Requires fresh cryptographic wallet authorization for ownership changes.
• Prevents stale or replayed signatures from being reused for account takeover.
• Restricts unlinking to authorized ownership flows.
• Preserves an auditable history of wallet verification and ownership changes.
• Does not provide an administrative mechanism to silently transfer wallet ownership.
• Keeps protocol authority within the smart contracts.
• Fails closed when required verification or security configuration is unavailable.
• Does not introduce Stellar/Freighter dependencies, production credentials, private keys, or other secrets.

Testing

• Added unit coverage for successful wallet linking.
• Tested invalid signatures, stale challenges, malformed requests, and unauthorized operations.
• Added replay/regression coverage to ensure previously used signatures cannot be reused.
• Tested wallet unlinking and ownership authorization boundaries.
• Added integration coverage across the relevant persistence and authentication boundary.
• Added recovery tests demonstrating that account recovery cannot centrally assume control of a wallet identity.
• Added regression coverage for the legacy unsafe wallet-linkage path addressed by the V2 implementation.

Migration & Rebuild Impact

• Added the required database migration for canonical wallet ownership and audit state.
• Ensured existing data can be migrated without introducing conflicting ownership records.
• Kept ownership history explicit and auditable.
• Verified affected schemas and generated artifacts remain synchronized.
• Preserved compatibility with the V2 indexer/API architecture.

Validation

• Ran the relevant unit and integration test suites.
• Ran lint and build checks.
• Validated database migrations and schema consistency.
• Ran applicable security checks.
• Verified replay and authorization protections.
• Confirmed sensitive wallet/signature material is not written to logs or test artifacts.
• Documented unrelated baseline failures separately where applicable.

Acceptance Criteria

• Define one canonical wallet ownership record with verification timestamps and audit history.
• Support linking only through fresh wallet signatures.
• Support unlinking only through fresh wallet signatures.
• Document and test recovery boundaries without centralized wallet takeover.
• Preserve smart-contract authority for protocol mutations.
• Cover success, failure, retry/replay, and authorization boundaries.
• Update affected documentation, schemas, migrations, and generated artifacts.
• Provide evidence mapping implementation and tests to each acceptance criterion.

closes #344
closes #345
closes #338
closes #343